A:

The following notes apply specifically to the Win32 platform, but much of the same work will be needed on the other platforms supported by Miles as well. We don't change our API specs lightly -- some of this stuff has remained untouched since the Windows 3.1 days! But code, like fish, doesn't get better with age. We believe that the library has benefited enormously from the housecleaning work we've put into MSS 7. And in fact, most of the changes have the same goal -- to make it easier for application developers to integrate MSS.

Virtually all of the changes in MSS 7 have been specific to the digital audio portion of the library. The good news is that if your application uses only the core 2D digital audio functionality in MSS 6, you can upgrade to the new system with almost no effort at all. Here are the basic steps that MSS digital-audio applications will need to follow in order to migrate to MSS 7:

• Change any remaining calls to the deprecated AIL_waveOutOpen and AIL_waveOutClose functions to AIL_open_digital_driver and AIL_close_digital_driver. If your application passed specific device IDs to the older functions, you will need to set the DIG_PREFERRED_WO_DEVICE and/or DIG_PREFERRED_DS_DEVICE preferences to those device IDs before calling AIL_open_digital_driver. You can still pass 1 or 2 as the channel parameter for AIL_open_digital_driver, but consider using an MSS_MC_SPEC enum value instead for multichannel support!

• Change AIL_filter_sample_attribute and AIL_set_filter_sample_preference to AIL_sample_stage_property. Applications that use only one of the eight available per-sample filter slots should specify SP_FILTER_0 for the new calls' stage parameters.

• If your application uses the Lagrangian interpolator filter, you should remove it. Similarly, the mono/stereo delay filters have been replaced with a single delay filter that can be used for both purposes.

• Applications that use AIL_load_sample_buffer must now call AIL_start_sample themselves. Low-level streamed ("double-buffered") samples are no longer started automatically as soon as the first buffer is loaded. It's not necessary to check the status of a low-level streaming sample before calling AIL_start_sample -- if it's already playing, the call will be ignored.

• Remove any calls to AIL_set_sample_type. The parameters formerly taken by AIL_set_sample_type have been moved to AIL_init_sample. It is not necessary to call AIL_init_sample prior to AIL_set_sample_file, AIL_set_named_sample_file, or AIL_set_sample_info.

• Remove any calls to AIL_allocate_file_sample and AIL_register_EOF_callback. Use AIL_set_sample_file or AIL_set_named_sample_file instead.

• We've removed a number of 'wrapper' functions that obscured the underlying HSAMPLE used by a DLS synthesizer or digital audio stream. These functions included AIL_DLS_set_reverb_levels, AIL_DLS_get_reverb_levels, AIL_stream_reverb_levels, AIL_set_stream_reverb_levels, AIL_DLS_processor, AIL_set_DLS_processor, AIL_stream_processor, AIL_set_stream_processor, AIL_stream_playback_rate, AIL_set_stream_playback_rate, AIL_set_stream_low_pass_cut_off, AIL_stream_low_pass_cut_off, AIL_set_stream_volume_pan, AIL_stream_volume_pan, AIL_filter_stream_attribute, AIL_set_filter_stream_preference, AIL_filter_DLS_attribute, and AIL_set_filter_DLS_preference. If your code uses any of these functions, you can replace them with calls to AIL_DLS_sample_handle and AIL_stream_sample_handle followed by the HSAMPLE-based version of the function you were calling.

If your application uses 3D sample handles, there's a bit more work ahead. The 3D and 2D digital audio subsystems -- and their associated data types -- have been combined in MSS 7. All of the 3D positioning calls can be used with ordinary HSAMPLES, rather than the specialized H3DSAMPLE type introduced with MSS 5.0 for 3D-positional samples. For the first time in MSS's history, you can use per-sample filters and play streaming audio, MP3/Ogg Vorbis files, or DLS sequences through EAX or DirectSound3D. The digital audio API is much cleaner now that it's no longer artificially divided into two incompatible halves. However, in the course of making these functional improvements, a number of significant changes to the 3D API emerged as necessary, desirable, or just plain overdue.

• Instead of opening a 2D driver with AIL_open_digital_driver and a separate 3D driver with a call to AIL_open_3D_provider, your MSS 7 application will need to acquire its 3D audio resources by calling AIL_open_digital_driver with channels equal to the enumerated MSS_MC_SPEC value corresponding to the desired output provider or discrete-channel format. (See FAQ for an explanation of the available MSS_MC_SPEC options.)

• AIL_enumerate_3D_providers, AIL_set_3D_provider_preference, AIL_enumerate_3D_provider_attributes, AIL_open_3D_provider, and AIL_close_3D_provider have been removed altogether. If your code formerly worked with provider-level 3D preferences or attributes, these are either obsolete now, or (in the DirectSound3D / EAX cases) accessible via the newly-added AIL_output_filter_driver_property function.

• The H3DSAMPLE type has been removed. Use HSAMPLEs everywhere you previously used H3DSAMPLEs. Most functions that formerly operated on H3DSAMPLEs were removed, including AIL_3D_sample_attribute, AIL_3D_sample_length, AIL_3D_sample_loop_count, AIL_3D_sample_offset, AIL_3D_sample_playback_rate, AIL_3D_sample_status, AIL_3D_sample_volume, AIL_allocate_3D_sample_handle, AIL_end_3D_sample, AIL_register_3D_EOS_callback, AIL_release_3D_sample_handle, AIL_resume_3D_sample, AIL_set_3D_sample_info, AIL_set_3D_sample_loop_block, AIL_set_3D_sample_loop_count, AIL_set_3D_sample_offset, AIL_set_3D_sample_playback_rate, AIL_set_3D_sample_preference, AIL_set_3D_sample_volume, AIL_start_3D_sample, AIL_stop_3D_sample, and AIL_3D_sample_count. Your application will need to move to the HSAMPLE-based versions of each of these functions.

• Code that previously used AIL_3D_sample_attribute and AIL_set_3D_sample_preference will need to use AIL_sample_stage_property with the SP_OUTPUT stage identifier instead. Note also that AIL_3D_sample_offset's HSAMPLE-based equivalent is AIL_sample_position -- which is distinct from AIL_sample_3D_position!

• Calls to AIL_set_3D_sample_effects_level should be replaced with AIL_set_sample_reverb_levels. The new function allows you to specify per-sample wet and dry levels separately. Per-sample wet level defaults to 0.0, so you must call AIL_set_sample_reverb_levels with a non-zero wet level for any HSAMPLE that needs to undergo reverb processing. As in previous versions of MSS, EAX applications must call AIL_set_digital_master_reverb_levels to set the master wet level to 0.0 explicitly if no enviromental processing is desired in the default ENVIRONMENT_GENERIC room type. This is a notable difference between the per-voice hardware providers and software mixer's behavior; in software, ENVIROMENT_GENERIC is completely dry.)

• AIL_set_sample_3D_distances now takes a third parameter, auto_3D_wet_atten, which determines whether or not reverb effects are attenuated with distance and cone direction. Applications should set this parameter to a nonzero value to emulate the old system's behavior with EAX 2, EAX 3, and EAX 4.

• The H3DPOBJECT type has been removed, as well as the AIL_auto_update_3D_position, AIL_open_3D_listener, AIL_close_3D_listener, AIL_open_3D_object, AIL_close_3D_object, AIL_3D_user_data, and AIL_set_3D_user_data functions. The remaining functions which took H3DPOBJECTs, including AIL_3D_orientation, AIL_3D_position, AIL_3D_velocity, AIL_3D_velocity_vector, AIL_set_3D_orientation, AIL_set_3D_position, AIL_update_3D_position, AIL_set_3D_velocity, and AIL_set_3D_velocity_vector have been replaced with versions specific to HSAMPLEs (AIL_sample_3D_orientation, AIL_sample_3D_position, AIL_sample_3D_velocity, AIL_set_sample_3D_orientation, AIL_set_sample_3D_position, AIL_set_sample_3D_velocity, AIL_set_sample_3D_velocity_vector) and HDIGDRIVERs (AIL_listener_3D_orientation, AIL_listener_3D_position, AIL_listener_3D_velocity, AIL_set_listener_3D_orientation, AIL_set_listener_3D_position, AIL_update_listener_3D_position, AIL_set_listener_3D_velocity, AIL_set_listener_3D_velocity_vector).

• Similarly, the functions AIL_set_3D_distance_factor, AIL_set_3D_doppler_factor, AIL_set_3D_rolloff_factor, AIL_set_room_type, AIL_3D_distance_factor, AIL_3D_doppler_factor, AIL_3D_rolloff_factor, and AIL_room_type now take an HDIGDRIVER rather than an HPROVIDER.

• AIL_set_3D_room_type and AIL_3D_room_type have been renamed to AIL_set_room_type and AIL_room_type, respectively. These functions are available even for samples that aren't undergoing 3D positioning by MSS. Likewise, AIL_set_3D_sample_occlusion, AIL_set_3D_sample_obstruction, AIL_set_3D_sample_exclusion, AIL_3D_sample_occlusion, AIL_3D_sample_obstruction, and AIL_3D_sample_exclusion have been renamed to AIL_set_sample_occlusion, AIL_set_sample_obstruction, AIL_set_sample_exclusion, AIL_sample_occlusion, AIL_sample_obstruction, and AIL_sample_exclusion.

• The remaining AIL_(set_)3D_sample...() and AIL_(set_)3D_listener...() functions have been renamed to AIL_(set_)sample_3D...() and AIL_(set_)listener_3D...() to reflect the fact that 3D positioning is now just another property of an HSAMPLE or HDIGDRIVER, rather than a feature implemented by a distinct '3D sample' or '3D listener' type.

• Note that an HSAMPLE's 3D properties are ignored by MSS's software mixer until the application requests 3D positioning support by calling AIL_set_sample_3D_position! Once enabled for a given HSAMPLE, 3D positioning can be disabled by releasing and reallocating the HSAMPLE, or by calling AIL_init_sample, AIL_set_sample_file, AIL_set_named_sample_file, or AIL_set_sample_info. Again, environmental effects such as reverb, occlusion, obstruction, and exclusion do not depend on a sample's 3D positional status; in MSS 7, only the functions whose names contain '3D' are involved with position and orientation in 3D space.

• The AIL_set_3D_speaker_type function and the MILES_SPEAKER_TYPE definitions have been removed. Speaker types are either specified by the end user via their Windows control panel or OEM configuration applet, or are implicit in the MSS channel specification passed to AIL_open_digital_driver (e.g., MSS_MC_51_DISCRETE or MSS_MC_STEREO).

value = AIL_sample_filter_attribute(S,"name,")

AIL_sample_filter_property(S,"name",&value,0,0)

AIL_set_sample_filter_preference(S,"name",&value)

AIL_sample_filter_property(S,"name",0,&value,0)